home *** CD-ROM | disk | FTP | other *** search
/ Just Call Me Internet / Just Call Me Internet.iso / prog / atari / m2 / cat3src / cat / doku / catproto.txt next >
Text File  |  1997-10-26  |  10KB  |  246 lines
  1. Dokumentation zum erweiterten CAT-Messageprotokoll      (29.04.96)
  2.  
  3. CAT kann mit einem Watchdog ber ein eigenes Protokoll kommunizieren.
  4. Dieses Protokoll wurde zur Version 2.0 von CAT um einiges erweitert,
  5. was aber nie komplett dokumentiert wurde. Dieses Dokument soll diese
  6. Lcke schliežen.
  7.  
  8. Die gesamte Kommunikation l„uft ber eine AES-Nachricht ab, die 
  9. Unterscheidung der einzelnen Anforderungen wird dabei ber Sub-Opcodes
  10. erledigt, die im Messagebuffer abgelegt werden. Es gilt folgender
  11. grundlegener Aufbau des AES-Messagebuffers:
  12.  
  13. mess[0] = 0x8000;       (* CatMsg *)
  14. mess[1] = apId;         (* Die von CAT bzw. dem Kommunikationspartner *)
  15. mess[2] = oversize;     (* immer 0 *)
  16. mess[3] = Sub-Opcode;   (* Siehe Tabelle *)
  17. mess[4-7]: Message-spezifische Daten
  18.  
  19. Folgende Sub-Opcodes sind definiert:
  20.  
  21.   (* Sub-Opcodes fr CatMsg *)
  22.  
  23.   enableWatchDog  = 0;
  24.   disableWatchDog = 1;
  25.   CatAffirm       = 2;
  26.  
  27.   CatAsk          = 3;
  28.   CatAccept       = 4;
  29.   CatForget       = 5;
  30.   CatGreetings    = 6;
  31.   CatTerminate    = 7;
  32.   CatFiltered     = 8;
  33.  
  34.   (* Sub-Opcodes fr das erweiterte Protokoll: *)
  35.  
  36.   WdwManager     = 9;
  37.   CatWinInfo     = 10;
  38.   CatWhatsIn     = 11;
  39.   CatPosition    = 12;
  40.   CatNewMess     = 13;
  41.   CatInform      = 14;      (* nicht implementiert *)
  42.   CatWinDirty    = 15;      (* nicht implementiert *)
  43.  
  44.   CatProtoVersion   = 1;    (* Das ist Version Nummer 1 *)
  45.   
  46.  
  47. Die Sub-Opcodes haben dabei folgende Bedeutung:
  48.  
  49. msg[3]  msg[4]
  50.  
  51. CatGreetings
  52.  6      0       CB->Cat Anmeldung bei Cat (evtl. kommt in mess[5] noch eine 
  53.                 Unterscheidung, ob es sich um einen WatchDog handelt, also 
  54.                 dort am besten eine Null eintragen). Fr etwas anderes als
  55.                 einen Watchdog darf in mess[5] keine 0 stehen.
  56.  6      version Cat-CB  Anmeldung angekommen, Protokoll-Versionsnummer zum 
  57.                 berprfen als Anlage. 
  58.  
  59. WdwManager
  60.  9      art     ACC->Cat, Anforderung der offenen Fenster, mess[5+6] 
  61.                 enthalten eine Adresse fr den Buffer, in den CAT 
  62.                 die Information hineinschreibt. mess[7] enth„lt die 
  63.                 Maximalanzahl an Fenstern, die in den Buffer passen 
  64.                 (pro Eintrag ein Integer, also 2 Byte)
  65.                 "art" enth„lt die Art der Fenster, die geliefert 
  66.                 werden sollen: 0: MsgFenster, 1: Editoren, 2: 
  67.                 Stichwortlisten
  68.                 Aktuell ist nur die Anforderung der Information ber
  69.                 die MsgFenster m”glich, mehr ist nicht implementiert.
  70.  9      art     Cat->ACC, offene Fenster, mess[5+6] enth„lt den Pointer 
  71.                 auf den Buffer, der vorher bergeben wurde. In dem Buffer
  72.                 steht die Liste der Fensterhandles, wenn das vom AES aus 
  73.                 klappt. mess[7] enth„lt die Anzahl der Fenster, die von 
  74.                 CAT geliefert werden.
  75.  
  76. CatWinInfo
  77. 10      whdl    ACC->Cat, Informationen anfordern. mess[5+6] enh„lt eine 
  78.                 Adresse, die sagt, wo die Informationen sollen , Format der 
  79.                 Information wie "winInfo" (siehe unten). mess[7] 
  80.                 enth„lt die L„nge des Buffers in mess[5+6].
  81.                 Achtung: Das eine Wort kann dazu evtl. nicht ausreichen!
  82. 10      whdl    Cat->ACC, Information wurde geschrieben, Bufferadresse 
  83.                 wieder in mess[5+6], L„nge in 7 (unver„ndert). 
  84.                 Wenn nichts geholt werden konnte, setzt CAT die Bufferadresse 
  85.                 und die L„nge auf 0.
  86. CatWhatsIn
  87. 11      whdl    CB->Cat, Welche Informationen werden im angegebenen Fenster 
  88.                 dargestellt? mess[5+6] enth„lt einen Zeiger auf folgende 
  89.                 Struktur:
  90.                  RECORD
  91.                    gruppe: CARDINAL;    (* Gruppennummer, 0 = Privat *)
  92.                    num   : CARDINAL;    (* interne Nachrichtenummer, 0-65534 *)
  93.                    size  : LONGCARD;    (* Anzahl Bytes fr alle Informationen,
  94.                                          * die man mit CatWinInfo anfordern kann
  95.                                          *)
  96.                  END;
  97.                  
  98. 11      whdl    Cat->CB mess[5+6] enth„lt wieder den Zeiger auf obige 
  99.                 Struktur
  100.                 Wenn nichts geholt werden konnte, setzt CAT die Bufferadresse 
  101.                 auf 0.
  102.  
  103. CatPosition
  104. 12      whdl    CB->Cat, Informationen ber MsgPositionen. mess[7] gibt an, 
  105.                 um welche Art es sich handelt: 0 Neue, 1 letzte Position, 2 
  106.                 ab Datum, 3 ab Nummer. In den letzten beiden F„llen wird in 
  107.                 mess[5+6] noch eine Adresse auf einen String bergeben, der 
  108.                 das Datum bzw. die ID enth„lt. Er ist nullterminiert.
  109. 12      whdl    Cat->CB, mess[5] interne Msgenummer; 0xffff heižt: Nicht 
  110.                 gefunden
  111.  
  112. CatNewMess
  113. 13      whdl    CB->Cat, neuen Inhalt setzen: mess[5] Gruppe mess[6] interne 
  114.                 MsgNummer
  115. 13      whdl    Cat->CB mess[5] = 0 -> hat geklappt, mess[5] # 0 -> geht 
  116.                 nich..
  117.  
  118. Zu der Funktion CatWinInfo ist eine n„here Erl„uterung unumg„nglich. 
  119. Insbesondere kann es passieren, daž das eine Wort in dem Buffer nicht 
  120. ausreicht fr die Gesamtanzahl der Bytes! Daher gilt zus„tzlich folgendes:
  121.  
  122. Wenn die per CatWhatsIn erfragte Gr”že nicht in ein Wort pažt 
  123. (d.h. > 65535 ist), dann ist der zu allozierende Buffer um 4 Byte zu 
  124. vergr”žern und das erste Langwort in diesem Buffer gibt dann die Gr”že
  125. des allozierten Buffers ohne diese 4 Byte an. In der Nachricht ist in msg[7]
  126. dann eine 0 zu bergeben!
  127. CAT gibt genau diesen Buffer auch wieder zurck, d.h. auch in dem 
  128. zurckgegebenen Buffer enthalten die ersten 4 Bytes ein Langwort mit der 
  129. Gesamtl„nge.
  130.  
  131. Was steht nun in diesem Buffer, nachdem CAT ihn gefllt hat? Einiges! CAT
  132. fllt den Buffer mit der internen Nachrichtenstruktur, mit allen Headertexten
  133. und mit dem kompletten Nachrichtentext (wenn denn der Buffer grož genug ist).
  134.  
  135. Das sieht dann so aus:
  136.   Nachrichtenstruktur
  137.   Infotexte         (* an n„chster gerader Adresse, ggf. Fllbyte davor *)
  138.   Nachrichtentext   (* an n„chster gerader Adresse, ggf. Fllbyte davor *)
  139.  
  140. Die Struktur am Anfang des Blocks ist folgende:
  141.  
  142.      MessageType = RECORD
  143.        MailNr,                      (* interne Nachrichtennummer *)
  144.        MailAnz   : CARDINAL;        (* Anzahl der Nachrichten in der Gruppe *)
  145.        KommentierteID : String255;  (* Referenz-Id (256 Bytes)              *)
  146.        fromOther : BOOLEAN;         (* Wurde die ID von der anderen Msg gelesen? *)
  147.        MailID,
  148.        Betreff,
  149.        Absender,
  150.        Empfaenger,
  151.        mid,
  152.        rid,
  153.        box,
  154.        gate,
  155.        mime,
  156.        name     : Str255Ptr; (* zeigen auf Positionen in "InfoStrings" *)
  157.        Gruppe   : CARDINAL;   (* Interne Gruppennummer *)
  158.        Datum,
  159.        StatusDatum            (* nur pers”nliche *)
  160.                 : DateType;
  161.        infoLen  : CARDINAL;   (* letztes Byte in <InfoStrings> *)
  162.        textLen  : CARDINAL;   (* letztes Byte im <Text> *)
  163.  
  164.        StatusBits : BITSET;   (* siehe unten *)
  165.  
  166.        up,
  167.        down,
  168.        left,                  
  169.        right  : CARDINAL;       (* interne Nummern der verknpften Nachrichten *)
  170.        KommentarAnzahl
  171.                 : CARDINAL;
  172.        statusDate      : LONGCARD;     (* Bei pers”nlichen: Statusdatum im MT-Format *)
  173.        tauschDate      : LONGCARD;     (* Datum im MausTauschformat *)
  174.        EigeneNachricht : BOOLEAN;
  175.        Status : CHAR;
  176.        Text,
  177.        InfoStrings  : BigTextPtr;       (* Zeiger auf Speicherbl”cke *)
  178.        distribution : tDistribution;    (* Distribution der Nachricht *)
  179.      END;
  180.  
  181. Folgende Typen werden dabei verwendet:
  182.  
  183. TYPE tDistribution = (dNone, dLokal, dMausNet, dNet);
  184.  
  185.      DateType    = ARRAY[0..18] OF CHAR;  (* Datum aus der Datenbank, 
  186.                                            * fertig formatiert als Text
  187.                                            *)
  188.  
  189.      String255   = ARRAY[0..255] OF CHAR;
  190.      Str255Ptr   = POINTER TO String255;
  191.  
  192.      BigText     = ARRAY[0..MAX(CARDINAL)] OF CHAR;
  193.      BigTextPtr  = POINTER TO BigText;
  194.  
  195. Die Statusbits sind wie folgt definiert:
  196.  
  197.       (* Statusbits einer Msg *)
  198. CONST bGelesen = 0; 
  199.       bFiltered = 1; 
  200.       bInteressant = 2; 
  201.       bTeilloeschung = 3;
  202.       bTotalloeschung = 4; 
  203.       bKommentieren = 5; 
  204.       bAntworten = 6; 
  205.       bUser1 = 7;
  206.       bUser2 = 8; 
  207.       bVererben = 9; 
  208.       bComToOwnMessage = 10;
  209.  
  210.       bOwnMessage = 14;
  211.  
  212.       bOldComToOwnMessage = 13;
  213.       (* da einige Betaversionen das so hatten, wird in einer šbergangsphase beides *)
  214.       (* erkannt und ggf. 13 entfernt und dafr 10 gesetzt *)
  215.  
  216.       (* Vorl„ufig bis bei der Maus die Message-Ids diesen Namen auch verdienen: *)
  217.       bOldDupe = 15;
  218.  
  219.  
  220.  
  221. Aužerdem steht oben noch so etwas dubioses wie "Bei pers”nlichen: 
  222. Statusdatum im MT-Format", und das bei einem LONGCARD, dabei weiž doch 
  223. jeder, daž das Datum im MausTausch ein String ist. Mit dieser
  224. Formulierung ist folgende Codierung gemeint: 
  225.  
  226.   (* Maus-Datumsstring in ein Cat-Datum umwandeln *)
  227. Ein Maustausch-Datum hat folgendes Format:
  228.  Jahr|Jahr|Jahr|Jahr|Monat|Monat|Tag|Tag|Stunde|Stunde|Minute|Minute
  229.  
  230. Von dem Jahr wird nun 1990 abgezogen und das ganze in eine Zahl in folgendem
  231. Format gewandelt:
  232.  Jahr|Jahr|Monat|Monat|Tag|Tag|Stunde|Stunde|Minute|Minute 
  233.  
  234. Aus einem Text "199604292210" wird somit die Zahl 0604292210.
  235.  
  236. Sekundenangaben im Maustauschformat werden hierbei nicht verarbeitet.
  237.  
  238.  
  239. Und noch eine Erl„uterung, und zwar zum Feld "fromOther". In diesem Feld 
  240. steht nur dann TRUE, wenn CAT beim Lesen der Nachricht die ID der kommentierten
  241. Nachricht schon aus dieser gelesen hat. Dies wird nur dann ausgefhrt, wenn die 
  242. ID nicht im Header enthalten ist, d.h. kann eigentlich gar nicht mehr auftreten.
  243. Fr externe Programme ist dieses Feld auch uninteressant, da die ID entweder
  244. in der Struktur vorhanden ist oder leer ist.
  245.  
  246.